四、config.txt 使用说明

Taco 系列产品采用配置文件 config.txt 替代传统 PC 的 BIOS 功能，该文件在 bootloader 阶段由系统读取。用户可在设备的 boot 分区（路径为 /boot/firmware/）中找到该配置文件。通过修改此文件，用户无需重新编译系统或修改硬件，即可灵活化配置设备的启动行为、硬件参数、网络服务等核心功能，是 Taco 系列产品实现灵活定制的关键入口。

4.1 Bootload 相关配置

4.1.1 bootdelay

bootdelay 命令用于在加载内核前强制等待指定秒数，其默认值为 0。当 SD 卡、eMMC 等存储设备在 Linux 系统启动前需要一定时间完成初始化（如硬件检测、信号同步）时，该命令将起到关键作用，确保系统与硬件设备的启动节奏同步，避免因存储设备未就绪导致的启动失败。

# 设置启动延时为 3 秒（给存储设备预留初始化时间）
bootdelay=3

4.1.2 boot_dtbname

boot_dtbname 参数用于指定 Taco 系列产品在启动时加载的设备树（Device Tree）文件名。设备树是描述硬件配置（如 GPIO 引脚分配、SPI/I2C 控制器、显示屏接口等）的数据结构，通过该参数可选择不同的硬件配置方案，适配不同型号的 Taco 设备或外接硬件。

# 指定设备树文件为 mes20 系列产品专用配置
boot_dtbname=tps-ea65xx-mes20.dtb

4.1.3 boot_disable_fan

boot_disable_fan 参数用于控制 Taco 系列产品的风扇启停逻辑。默认状态下，系统启动后风扇会根据硬件温度自动开启（温度过高时启动散热）；若启用该配置项，将强制禁用风扇运行（适用于低功耗场景或外部散热充足的环境）。

# 在系统启动后强制禁用风扇
boot_disable_fan=on

4.1.4 eeprom_write_protect

eeprom_write_protect 参数用于控制 Taco 系列产品中 EEPROM（电可擦可编程只读存储器）的写保护状态。EEPROM 通常存储设备序列号、硬件校准参数等关键信息，通过该参数可防止数据被意外修改，或允许必要时更新数据。

• 取值说明：
  • 1 表示开启写保护（禁止写入）
  • 0 表示关闭写保护（允许写入）

# 开启 EEPROM 写保护（防止关键数据被误修改）
eeprom_write_protect=1

4.1.5 board_power_monitor

该参数用于控制基于 TI INA226 芯片的板载电源监控模块的启用与禁用状态，核心功能是决定系统是否启动对电路中电压、电流和功率参数的实时测量与监控（数据可用于功耗分析、硬件故障排查）。

• 取值说明：
  • on 表示启用监控
  • off 表示禁用监控（可降低微小功耗）

# 禁用板载电源监控模块
board_power_monitor=off

4.1.6 ota_serverip

该参数指定 OTA（Over-The-Air，空中下载）升级服务器的 IP 地址，为设备进行 OTA 升级时提供目标服务器的网络定位。设备启动 OTA 升级流程时，会通过此 IP 地址连接服务器，获取固件包并完成升级。

# 指定 OTA 升级服务器 IP 为 192.168.56.99
ota_serverip=192.168.56.99

4.1.7 serverip

serverip 用于指定 PXE 网络启动和 NFS 网络文件系统的服务器 IP 地址，是设备通过网络启动或挂载网络存储时的核心配置项。该参数为两类网络服务提供统一的服务器地址：

1. PXE 启动服务：当设备启用 PXE 网络启动（如 force_pxe = true）时，会通过此 IP 地址定位 PXE 服务器，获取启动镜像、引导程序等启动所需文件。
2. NFS 服务：当设备需要挂载网络文件系统（NFS）时，会以该 IP 作为目标服务器地址，访问共享的根文件系统或数据目录。

关联场景：

• 与 force_pxe 配合：当 force_pxe = true 强制启用 PXE 启动时，设备会自动使用此 IP 连接 PXE 服务器，并同步启用 NFS 挂载（即使未单独配置 NFS 地址）。
• 独立 NFS 配置：若单独启用 NFS（nfs = true），无需 PXE 启动时，该参数也会作为 NFS 服务器的默认地址。

# 设备会将 IP 为 192.168.56.99 的服务器同时作为
# PXE 启动源和 NFS 文件服务器，确保网络启动和文件
# 访问的一致性。
serverip=192.168.56.99

4.1.8 force_pxe

force_pxe 是用于强制启用 PXE 网络启动模式的配置参数。PXE（Preboot Execution Environment，预启动执行环境）是一种通过网络从服务器加载操作系统或启动镜像的技术，无需依赖本地存储设备（如硬盘、SD 卡）。 当 force_pxe 设为 true 时，设备启动过程中会强制优先尝试通过 PXE 协议从网络获取启动数据，跳过本地启动介质的检测流程，确保网络启动方式被优先执行。默认状态下为 false（优先从本地存储启动）。

# 禁用强制 PXE 启动（默认从本地存储启动）
force_pxe=false

4.1.9 nfs

nfs 是用于控制设备 NFS（Network File System，网络文件系统）客户端功能启用与禁用的核心配置参数，主要作用是决定设备是否允许通过网络连接远程 NFS 服务器，并挂载服务器上的共享文件系统（如根目录、数据目录等），进而实现网络存储的访问与使用。

• 功能状态控制：通过参数取值（true/false），切换设备的 NFS 功能模式 —— 启用时，设备可基于预设的 serverip（NFS 服务器 IP）连接远程服务器，挂载共享目录并像访问本地存储一样读写网络文件；禁用时，设备会关闭 NFS 客户端逻辑，仅依赖本地存储（如 SD 卡、eMMC、硬盘）进行文件操作。

• 适配网络存储需求：根据使用场景灵活选择是否依赖 NFS —— 当设备需要访问集中式网络存储（如批量部署的嵌入式设备共享服务器资源、无本地存储的瘦客户端）时启用；当仅需本地存储独立运行、或网络环境受限（无 NFS 服务器、网络不稳定）时禁用。
  配置注意事项：

• 配置 nfs 前，需先确认 force_pxe 的状态，避免因 PXE 强制启用导致 nfs 配置冲突；

• 若需启用 NFS，需同步配置 serverip 参数（指定 NFS 服务器 IP 地址），否则设备无法定位目标服务器；

• 切换 nfs 状态后，需重启设备以确保配置生效。

# 启用 NFS 功能，依赖 serverip 连接服务器
nfs=ture
serverip=192.168.56.99
force_pxe=true  # 同时启用 PXE 启动，与 NFS 共享服务器 IP

4.1.10 rootpath

rootpath为nfs文件系统要挂载的服务器路径。

rootpath=/srv/nfs/rootfs

4.1.11 disable_autoreboot

disable_autoreboot 是用于控制设备是否自动重启的配置参数，主要作用是决定系统在特定场景下（如完成固件升级、配置更新、触发错误恢复机制后）是否执行自动重启动作。 适用场景：

• 自动化部署流程：在设备批量配置、固件升级等场景中，设置 disable_autoreboot = false 可让设备在操作完成后自动重启生效；
• 调试与维护场景：设置 disable_autoreboot = true 可避免系统在调试过程中因触发自动重启而中断工作，便于查看日志、排查问题；
• 任务连续性保障：对于需要长时间运行的任务（如数据采集、服务部署），禁止自动重启可确保任务不被中途打断。

# 禁止系统自动重启（适用于调试或长任务场景）
disable_autoreboot=true

4.2. 内存配置

内存配置模块通过精细化参数定义 Taco 系列产品的内存资源分配规则，涵盖全局内存容量限定、专用硬件单元（如 NPU）内存预留、系统核心模块内存分区等场景，确保内存资源在不同硬件单元与系统模块间高效分配，适配多样化业务负载（如 AI 计算、系统调度）需求。

4.2.1 total_mem

total_mem 参数用于强制指定 Taco 系列产品的可用物理内存总量，优先级高于硬件自动检测结果，可突破硬件默认内存容量限制，实现 “内存容量模拟” 或 “内存资源裁剪”，适用于兼容性测试、资源受限场景（如模拟低内存型号设备运行）。 参数说明：

• 单位：兆字节（MB，1 MB = 1024 × 1024 字节）；
• 取值范围：需小于等于设备实际物理内存容量（如 16 GB 内存设备最大可设为 16384 MB），且需为内存硬件支持的 “对齐值”（通常为 2 的整数次幂，如 2048 MB、4096 MB）；
• 默认行为：未配置时，系统自动检测并使用设备全部物理内存。

total_mem=8192

4.2.2 tacosys_mem_addr & tacosys_mem_size

tacosys_mem_addr 与 tacosys_mem_size 用于为 Taco 系统核心内存管理模块（tacosys）划分独立内存区域，该区域专供 tacosys 模块进行内存资源调度（如内存页分配、缓存管理、多模块内存隔离），确保系统内存管理功能的独立性与稳定性，避免受其他模块内存操作的干扰。

# 配置 tacosys 专用内存起始地址为 0x140000000
# 容量为 0x80000000 字节（2 GB）
tacosys_mem_addr=0x140000000
tacosys_mem_size=0x80000000

4.3. 频率配置

频率配置模块通过精准设定核心硬件单元的运行时钟频率，实现 Taco 系列产品在性能、功耗与稳定性之间的动态平衡。合理配置频率参数可适配多样化场景需求 —— 如高负载计算场景提升频率以增强性能，低功耗场景降低频率以减少能耗。

4.3.1 ddr_freq

ddr_freq 参数用于在 DDR 内存初始化阶段设定其运行频率，直接决定内存数据读写速率（带宽），是影响系统整体性能的核心参数（内存带宽不足会成为 CPU、NPU 等计算单元的性能瓶颈）。 参数说明：

• 单位：赫兹（Hz），通常以 “1000000” 为单位表示兆赫兹（MHz，如 1066000000 = 1066 MHz， 2133000000 = 2133 MHz）；
• 取值约束：需为 DDR 硬件支持的标准频率（如 DDR4 支持 2133 MHz 等），具体范围参考 Taco 产品硬件手册；
• 性能影响：频率越高，内存带宽越大（如 2133 MHz 对应带宽高于 1866 MHz），可提升 CPU/NPU 访问内存的效率，但会增加功耗与散热压力。

# 配置 DDR 内存运行频率为 2133 MHz（2133000000 Hz）
ddr_freq=2133000000

4.3.2 cpu_freq、cpu_freq_min、cpu_freq_max

该组参数用于控制 CPU 核心的运行频率及动态调节范围，通过调整 CPU 时钟频率（由 APLL 锁相环电路生成），平衡计算性能与能耗：

• cpu_freq：设定 CPU 的默认运行频率（静态模式下生效）；
• cpu_freq_min：设定 CPU 动态调频时的最低频率下限；
• cpu_freq_max：设定 CPU 动态调频时的最高频率上限。

参数说明

• 单位：赫兹（Hz），通常以 “1000000” 为单位表示兆赫兹（MHz，如 1584000000 = 1584 MHz）；
• 调节原理：通过改变 APLL 的倍频 / 分频系数实现频率调整（如倍频系数越高，输出频率越高）；
• 动态调频逻辑：当系统负载升高时，CPU 自动提升至接近 cpu_freq_max 的频率；负载降低时，降至接近 cpu_freq_min 的频率，兼顾性能与功耗。

配置约束

• cpu_freq_min ≤ cpu_freq ≤ cpu_freq_max（默认频率需在动态调节范围内）

# CPU 默认运行频率为 1584 MHz
cpu_freq=1584000000
# 动态调频范围：最低 1000 MHz，最高 1584 MHz（锁定最高性能）
cpu_freq_min=1000000000
cpu_freq_max=1584000000

4.3.3 enc_freq

enc_freq 参数用于设定视频编码器（如 H.264/H.265 编码器）的运行频率，直接影响视频编码性能（如编码速率、支持的分辨率 / 帧率）。 参数说明

• 单位：赫兹（Hz），以 “1000000” 为单位表示兆赫兹（MHz，如 500000000 = 500 MHz）；
• 性能关联：频率越高，编码器处理能力越强 —— 可支持更高分辨率（如 4K）、更高帧率（如 60 fps）的视频编码，或缩短单帧编码耗时；
• 默认值：500 MHz。

#默认频率为 500 MHZ
enc_freq=500000000

4.3.4 dec_freq

dec_freq 参数用于设定视频解码器（如 H.264/H.265 解码器）的运行频率，决定设备解码高清视频的能力（如支持的分辨率、帧率及解码流畅度）。 参数说明

• 单位：赫兹（Hz），以 “1000000” 为单位表示兆赫兹（MHz，如 594000000 = 594 MHz）；
• 性能影响：频率越高，解码器处理能力越强，可流畅解码更高码率、更高分辨率的视频；
• 默认值：594 MHz。

# 配置视频解码器运行频率为 594 MHz
dec_freq=594000000

4.3.5 npu_freq

npu_freq 参数用于设定 NPU（神经网络处理单元）的运行频率，是影响 AI 计算性能的核心参数（NPU 频率直接决定模型推理速度）。 参数说明

• 单位：赫兹（Hz），以 “1000000” 为单位表示兆赫兹（MHz，如 800000000 = 800 MHz）；
• 性能关联：频率越高，NPU 算力越强，可缩短深度学习模型（如目标检测、图像分类）的推理耗时；
• 默认值：800 MHz。

# 配置 NPU 运行频率为 800 MHz
npu_freq=800000000

4.4. 温度与电压配置

温度与电压配置模块通过设定硬件保护阈值和核心供电参数，保障 Taco 系列产品在不同负载下的运行安全性与稳定性，同时为性能优化提供基础电气条件。

4.4.1 temp_limit

temp_limit 参数用于设置 Taco 系列产品硬件的过热保护触发阈值。当系统温度达到或超过该设定值时，硬件会断电保护，以防止设备因过热导致性能下降、寿命缩短或硬件损坏。 核心功能：

• 作为硬件过热保护的“安全阀值”：实时监测核心硬件的温度，当任一监测点温度达到或超过该阈值时，触发硬件级断电保护，强制切断供电以阻止温度持续上升；
• 平衡设备性能与安全性：既允许硬件在合理温度范围内满负荷运行（发挥最大性能），又能在异常过热时快速响应，避免因高温导致的芯片性能不可逆衰减、焊点老化加速或直接硬件损坏。

# 数值单位为摄氏度（℃）
# 表示当硬件温度达到 100℃ 时，触发过热断电保护。
temp_limit=100

注意事项

• 阈值不可设置过高（如超过 105℃）：现代芯片的结温上限通常为 125℃，但长期接近该温度会显著缩短寿命；
• 频繁触发保护需排查原因：若设备未运行高负载任务却频繁断电，可能是散热系统故障（如风扇停转、散热片积灰），需优先检修硬件而非提高阈值。

4.4.2 over_voltage

over_voltage 参数用于设置 CPU 内核电压的上限值。通过调整该参数，可实现 CPU 性能与稳定性之间的平衡，适用于超频、低功耗优化等场景。

单位：微伏（μV） 默认值：1100000

over_voltage=1100000

4.5 spi

4.5.1 spi_n_m

该参数用于在系统中配置 SPI 设备的硬件连接关系，明确指定设备所挂载的 SPI 总线及对应的片选（Chip Select, CS）信号。其中：

• n：表示 SPI 总线的编号（从 0 开始计数），对应硬件中不同的 SPI 控制器实例
• m：表示设备在目标总线上的片选信号编号（从 0 开始计数），用于唯一标识总线上的不同设备

spi0_0=on //设置spi0设备片选0使能

4.5.2 spi_speed

spi_speed 参数用于配置 SPI 总线的通信时钟频率，直接决定了主控制器与从设备之间的数据传输速率。通过调整该参数，可以：

• 匹配不同 SPI 设备的最高支持频率
• 平衡数据传输速度与信号稳定性
• 优化系统功耗（高频通常伴随更高功耗）

spi_speed=4000000 //设置spi设备的工作频率为 4M
ospi_speed=4000000  //设置spi设备的工作频率为 4M

4.5.3 spi_fastr

spi_fastr 参数用于为闪存设备启用快速读取（Fast Read）功能。该功能通过优化 SPI 总线的时序，在不显著增加功耗的前提下，提升闪存设备的数据读取速度，适用于对读取性能有较高要求的场景（如代码执行、数据缓存）。

spi_fastr=on

4.5.4 spi_dma

spi_dma参数用于启用 SPI 总线的 直接内存访问（DMA）功能，允许 SPI 控制器直接与系统内存进行数据传输，无需 CPU 干预。

dtparam=spi_dma=on

4.5.5 spi

spi参数用于启用或禁用系统中的 SPI（Serial Peripheral Interface）总线控制器及相关设备。通过该参数，可灵活配置 SPI 接口的工作状态.

dtparam=spi=on

4.5.6 spi_cs

spi_cs 是 SPI 总线配置中的核心参数，用于在 “一主多从” 的 SPI 架构中，由主设备指定当前待通信的从设备（如传感器、存储芯片、显示屏等），本质是 主设备与目标从设备的 “通信授权开关”。

spi0_cs=1 //片选值为1

4.6 uart

4.6.1 ctsrts

• 功能：启用或禁用UART接口的硬件流控制（CTS/RTS）
• 默认值：off（禁用）
• 配置示例：

dtparam=ctsrts=on  # 启用 CTS/RTS 硬件流控制

4.6.2 uart

• 功能：启用或禁用指定 UART 设备
• 配置示例：

dtparam=uart0=on

4.6.3 baudrate

baudrate 参数用于设置 Taco 系列产品在系统初始化阶段的 UART 通信波特率。默认值为 115200。

baudrate=115200

4.6.4 rs485_invert_rts

该参数配置 RS485 通信中 RTS 引脚的有效电平极性（RTS 是"请求发送"信号，用于控制 RS485 芯片的收发切换）。 该参数只要定义即为 rs485-rts-active-low。

rs485_invert_rts=1  //RTS 信号开启延迟 1 毫秒

4.6.5 rs485_rts_on_delay

设置从 RTS 引脚激活（切换为发送模式）到实际开始发送数据之间的延时，确保 RS485 芯片有足够时间完成状态切换。

• 单位：毫秒（ms） 例如：若值为 10，表示 RTS 引脚切换为发送状态后，等待 10 ms 再开始发送数据——这是为了避免因 RS485 芯片切换速度较慢，导致开头的数据包丢失（芯片未准备好发送时，数据会被截断）。

rs485_rts_on_delay=1

4.6.6 rs485_rts_off_delay

设置从发送数据完成到 RTS 引脚关闭（切换为接收模式）之间的延时，确保最后一段数据完全发送出去。

# 若值为 5，表示数据发送完成后，等待5ms再将RTS引脚切换为接收状态
# 这是因为 RS485 总线的信号传输有延迟，若立即切换到接收模式，
# 可能导致最后几个字节还未发送完毕就被中断，造成数据不完整。
dtapram=rs485_rts_off_delay=5

注意：RS485 是半双工通信（同一时间只能发送或接收），这三个参数共同确保收发切换的可靠性：

1. rs485_invert_rts：确定 RTS 引脚用高电平还是低电平触发发送模式（匹配硬件逻辑）；
2. rs485_rts_on_delay：给 RS485 芯片留足切换到发送模式的准备时间；
3. rs485_rts_off_delay：确保最后一段数据发送完毕后，再切换回接收模式。

配置错误可能导致：数据发送/接收失败、数据包丢失、总线冲突（同时收发）等问题，需严格参考 RS485 芯片的数据手册和硬件设计进行匹配。

4.7 i2c

4.7.1 i2cX

• 功能：启用或禁用指定 i2cX 设备
• 配置示例：

i2c0=on

4.7.2 i2c_freq

• 功能：配置 i2c 设备的工作频率
• 配置示例：

dtparam=i2c0_freq=400000  //400K

4.8 i2s

I2S（Inter-IC Sound）总线用于音频设备之间的数字音频数据传输，支持 DMA 模式和中断模式两种传输方式。本节介绍如何通过设备树参数（dtparam）配置 I2S 总线的工作模式及相关属性。

4.8.1 i2s_dma

启用 I2S 总线的 DMA（直接内存访问）传输模式，适用于大数据量、高实时性的音频传输。

i2s_dma=1 //表示使能DMA模式

4.8.2 i2s_irq

启用 I2S 总线的中断驱动传输模式，适用于数据量较小、延迟敏感的场景。

i2s_irq=1 //表示使能中断模式

4.8.3 i2s

控制 I2S 总线的整体启动状态。

i2s=on

4.8.4 i2s_card_name

自定义 ALSA 声卡的名称，用于系统识别和用户空间应用显示。

4.9 display

4.9.1 hactive（水平有效像素）

hactive 是定义DPI显示水平分辨率的核心参数，直接决定屏幕横向可显示的有效像素数量，是画面宽度的“基准标尺”。 核心功能：

• 设定显示画面的横向有效像素值，该值与显示器物理分辨率的水平维度完全对应（如显示器标注 “1920 × 1080”，则 hactive 需配置为 1920）；
• 与后续水平时序参数（hfp、hsync、hbp）共同构成完整的水平扫描周期，有效像素部分是用户实际可见的画面区域。
• 单位：像素（px），取值为正整数，需与显示器支持的水平分辨率一致（如 800、1280、1920、2560 等）；
• 示例：hactive = 1920 表示屏幕横向显示 1920 个有效像素，对应1080p分辨率的水平维度；hactive = 800 对应 800 × 480 等小尺寸屏幕。

配置影响：

• 若取值大于显示器最大支持水平分辨率：画面横向会被裁剪（仅显示左侧部分内容）；
• 若取值小于显示器物理水平分辨率：画面横向会出现黑边（右侧空白）；
• 需与“水平时序总长度”（hactive + hfp + hsync + hbp）匹配显示器的水平扫描能力，避免超出像素时钟频率支持范围。

hactive=1024

4.9.2 hfp（水平前廊）

hfp（Horizontal Front Porch，水平前廊）是水平扫描时序的“缓冲参数”，定义水平有效像素结束后、水平同步脉冲开始前的空白像素数量，是保障行扫描过渡稳定的关键。 核心功能:

• 为显示器提供“行切换准备时间”：当一行有效像素显示完成后，显示器需要短暂时间（对应 hfp 的像素周期）调整扫描电路状态（如电子束从行尾向行首移动的初始阶段），避免下一行有效像素“提前显示”导致画面边缘重叠；
• 补偿信号传输延迟：DPI 接口的像素数据与同步信号存在微小传输延迟，hfp的空白像素可抵消该延迟，确保同步信号与下一行数据精准对齐。

单位:

• 单位：像素（px）；

配置影响：

• 取值过小：显示器来不及准备行切换，会导致画面横向边缘（右侧）出现裁剪、模糊或错位；
• 取值过大：会浪费水平扫描带宽（总周期变长），可能导致刷新率降低（如原本 60 Hz 降至 55 Hz）。

hfp=180

4.9.3 hsync（水平同步脉冲宽度）

hsync（Horizontal Sync Pulse Width，水平同步脉冲宽度）是显示器识别“行切换”的“信号标识”，定义水平同步脉冲的持续像素数量。 核心功能：

• 发送“行结束”指令：水平同步脉冲是低电平或高电平的特定信号（由hsync_invert决定），脉冲期间，显示器明确接收到“当前行已结束，准备接收下一行”的指令，停止处理有效像素数据，进入行切换状态；
• 统一扫描节奏：所有DPI显示器均依赖同步脉冲同步行扫描节奏，确保不同设备（如主控与屏幕）的行处理速度一致。

单位：

• 单位：像素（px） 配置影响：
• 取值过小：同步脉冲信号过短，显示器无法识别行切换指令，导致画面横向撕裂（多行数据重叠）；
• 取值过大：会占用更多水平扫描周期，降低有效显示区域占比（空白部分增加）。

hsync=20

4.9.4 hbp（水平后廊）

hbp（Horizontal Back Porch，水平后廊）是水平扫描时序的“收尾缓冲”，定义水平同步脉冲结束后、下一行水平有效像素开始前的空白像素数量。 核心功能：

• 补偿扫描电路延迟：水平同步脉冲结束后，显示器的扫描电路（如电子束）需要时间从行尾完全移动到行首，hbp的空白像素周期用于覆盖该延迟，确保下一行有效像素开始时，扫描电路已处于“就绪状态”；
• 稳定信号电平：同步脉冲结束后，信号电平需要时间恢复到有效数据的电平范围，hbp可避免因电平不稳定导致的下一行开头像素色彩异常。

单位：

• 单位：像素（px） 配置影响：
• 取值过小：扫描电路未完成行首定位，下一行有效像素会从屏幕横向中间开始显示（左侧出现裁剪）；
• 取值过大：与 hfp 类似，会浪费带宽，可能降低刷新率。

hbp=160

4.9.5 vactive（垂直有效行数）

vactive 是定义 DPI 显示垂直分辨率的核心参数，直接决定屏幕纵向可显示的有效像素行数，与 hactive 共同构成屏幕的“整体分辨率”。 核心功能:

• 设定显示画面的纵向有效行数，与显示器物理分辨率的垂直维度完全对应（如显示器标注“1920 × 1080”，则 vactive 需配置为 1080）；
• 纵向有效行数是“帧画面”的基础——一帧完整画面由 vactive 行水平像素构成，行数越多，画面纵向细节越丰富。

取值与单位:

• 单位：行数（对应水平像素行），取值为正整数（如 480、720、1080、2160 等）；
• 示例：vactive = 1080 表示一帧画面包含 1080 行水平像素，配合 hactive = 1920 即构成 1080p（全高清）分辨率；vactive = 480 配合 hactive = 800 构成800 × 480（WVGA）分辨率。 配置影响:
• 若取值大于显示器最大垂直分辨率：画面纵向会被裁剪（仅显示上半部分）；
• 若取值小于显示器物理垂直分辨率：画面纵向会出现黑边（下半部分空白）；
• 需与垂直时序总长度（vactive + vfp + vsync + vbp）匹配显示器的垂直扫描频率（刷新率）。

vactive=600

4.9.6 vfp（垂直前廊）

vfp（Vertical Front Porch，垂直前廊）是垂直扫描时序的“帧切换准备参数”，定义垂直有效行数结束后、垂直同步脉冲开始前的空白行数。 核心功能：

• 为显示器提供“帧切换准备时间”：当一帧画面的 vactive 行全部显示完成后，显示器需要时间调整垂直扫描电路（如电子束从屏幕底部向顶部移动的初始阶段），vfp 的空白行数用于覆盖该准备过程；
• 避免帧间重叠：确保上一帧的最后一行与下一帧的第一行不会因切换过快而重叠显示（导致画面纵向撕裂）。

单位：

• 单位：行数

配置影响：

• 取值过小：显示器来不及准备帧切换，会导致画面纵向底部出现裁剪或与下一帧顶部重叠；
• 取值过大：会增加帧扫描总周期，降低刷新率（如 60 Hz 降至 58 Hz）。

vfp=12

4.9.7 vsync（垂直同步脉冲宽度）

vsync（Vertical Sync Pulse Width，垂直同步脉冲宽度）是显示器识别“帧切换”的“核心信号”，定义垂直同步脉冲的持续行数，是解决画面“撕裂”的关键。 核心功能：

• 发送“帧结束”指令：垂直同步脉冲是特定电平的信号（由 vsync_invert 决定），脉冲期间，显示器明确接收到“当前帧已结束，准备接收下一帧”的指令，停止处理有效像素行，进入垂直扫描复位状态（电子束从底部返回顶部）；
• 同步帧率与刷新率：若启用“垂直同步”功能（如游戏、视频播放），主控会等待 vsync 信号后再输出下一帧数据，确保帧输出速度与显示器刷新率一致，彻底避免画面撕裂。

单位：

• 单位：行数

配置影响：

• 取值过小：同步脉冲无法被显示器识别，导致帧切换混乱，画面出现严重纵向撕裂；
• 取值过大：会增加帧总周期，轻微降低刷新率（如 60 Hz 降至 59.5 Hz）。

vsync=5

4.9.8 hsync_invert（水平同步信号极性）

hsync_invert 是控制水平同步信号有效电平的极性参数，决定显示器以“高电平”还是“低电平”作为水平同步信号的有效触发条件，是解决横向显示兼容问题的关键。 核心功能：

• 适配显示器的同步信号电平要求：不同厂商的DPI显示器对水平同步信号的有效电平定义不同（部分为高电平有效，部分为低电平有效），hsync_invert 通过“反转”信号电平，确保显示器能正确识别同步指令；
• 修正横向显示异常：若同步极性不匹配，显示器会将同步信号误认为有效像素数据，导致画面横向错位、闪烁或无显示。

取值：

• 0（默认）：水平同步信号不反转，以高电平为有效触发（主流显示器默认配置）；
• 1：水平同步信号反转，以低电平为有效触发（仅适配标注“水平同步低电平有效”的显示器）。

配置影响：

• 极性错误（如显示器需低电平有效，但配置为 0）：画面横向会出现无规律错位、滚动或黑屏；

hsync_invert=0

4.9.9 vsync_invert（垂直同步信号极性）

vsync_invert 是控制垂直同步信号有效电平的极性参数，决定显示器以“高电平”还是“低电平”作为垂直同步信号的有效触发条件，直接影响帧切换的稳定性。 核心功能：

• 适配显示器的垂直同步电平要求：与 hsync_invert 类似，不同显示器对垂直同步信号的有效电平定义不同，vsync_invert 通过反转信号，确保显示器正确识别“帧结束”指令；
• 避免帧间撕裂与黑屏：若极性不匹配，显示器无法同步帧切换，会导致画面纵向撕裂、帧丢失或黑屏。

取值：

• 0（默认）：垂直同步信号不反转，以高电平为有效触发（主流配置）；
• 1：垂直同步信号反转，以低电平为有效触发（适配标注“垂直同步低电平有效”的显示器）。

配置影响：

• 极性错误：画面会出现严重纵向撕裂（如上下帧数据重叠）、刷新率骤降（如 60 Hz → 30 Hz）或完全黑屏；
• 关联功能：若启用“垂直同步”（VSync）功能，极性错误会导致 VSync 失效，无法解决撕裂问题。

vsync_invert=0

4.9.10 de_invert（数据使能信号极性）

de_invert 是控制DPI接口数据使能（DE）信号有效电平的参数，DE 信号是“有效像素数据”的“开关标识”，仅当DE信号有效时，显示器才会接收并显示像素数据。 核心功能：

• 定义有效数据的触发条件：DE 信号（Data Enable）是DPI接口的辅助控制信号，与像素数据同步传输——当DE有效时，显示器确认当前传输的是“需要显示的有效像素”；当DE无效时，显示器忽略传输的数据（视为空白）；
• 适配显示器 DE 电平要求：部分显示器默认高电平DE有效，部分默认低电平有效，de_invert 通过反转信号确保有效数据被正确识别。

取值：

• 0（默认）：DE 信号不反转，以高电平为有效（即 DE = 1时，显示器接收像素数据）；
• 1：DE 信号反转，以低电平为有效（即 DE = 0时，显示器接收像素数据）。

配置影响：

• 极性错误：显示器会错误地将空白数据视为有效像素（导致画面全白/全黑），或忽略有效数据（导致黑屏）；
• 适用场景：部分简化版 DPI 显示器可能不支持 DE 信号（仅依赖同步信号），此时 de_invert 配置无效，但需确保参数与显示器支持的模式一致。

de_invert=0

4.9.11 pixclk-invert（像素时钟极性）

pixclk-invert 是控制 DPI 接口像素时钟（pixclk）采样边沿的参数，像素时钟是显示器采集像素数据的“时间基准”，pixclk-invert 决定显示器在时钟的“上升沿”还是“下降沿”采集数据。 核心功能：

• 同步数据采样节奏：像素时钟是固定频率的方波信号（如 1920 × 1080 @ 60 Hz 需 148.5 MHz），显示器每接收一个时钟周期，采集一个像素数据；
• 适配数据传输延迟：像素数据从主控传输到显示器存在微小延迟（因 PCB 布线长度差异），pixclk-invert 通过选择不同采样边沿（上升沿/下降沿），补偿该延迟，确保采集到的是稳定的像素数据（而非电平跳变中的不稳定数据）。

取值：

• 0（默认）：像素时钟不反转，显示器在时钟的上升沿（从低变高的瞬间）采集像素数据（主流配置）；
• 1：像素时钟反转，显示器在时钟的下降沿（从高变低的瞬间）采集像素数据（适配数据传输延迟较大的场景）。

配置影响：

• 极性错误：显示器会采集到“电平未稳定”的像素数据，导致画面出现色彩异常（如偏色、杂色点）、像素错位（如相邻像素颜色混淆）或完全黑屏；
• 验证方法：若配置后画面色彩混乱，可尝试切换取值，通常能解决采样边沿不匹配问题。

pixclk-invert=0

时序与极性的关联性

1. 水平时序总周期 = hactive + hfp + hsync + hbp → 决定水平扫描频率（与像素时钟频率相关）；
2. 垂直时序总周期 = vactive + vfp + vsync + vbp → 决定垂直扫描频率（即刷新率，如 60 Hz）；
3. 极性参数（hsync_invert、vsync_invert 等）需与显示器硬件要求完全匹配，否则时序参数配置正确也无法正常显示。

4.9.12 backlight_pwm_func

配置 backlight_pwm_func 指定的 GPIO 引脚，将其从“普通 GPIO 功能”切换为“PWM 功能”，确保引脚能正确输出 PWM 波形（否则引脚仅能输出高低电平，无法实现亮度调节）。

• 默认值和可选值：
  • 默认值：0（pwm 输出）
  • 可选值：0，1，2

backlight_pwm_func=0

4.9.13 backlight_gpio（GPIO 背光控制引脚）

backlight_gpio 参数用于指定用于 开关式背光控制 的 GPIO 引脚，仅支持“亮/灭”两种状态（无法调节亮度），适用于无需亮度渐变的简单场景（如低成本单色 LCD）。

• 取值格式：需参考 GPIO 引脚图，避免与其他外设冲突
• 工作逻辑：
  • 当该 GPIO 引脚输出 高电平 时，背光点亮；
  • 输出 低电平 时，背光熄灭

# 启用 PWM，指定 GPIO8 输出 PWM 背光信号
backlight_pwm=on
backlight_pwm_gpio=8

4.9.14 backlight_pwm

backlight_pwm 参数用于指定用于背光控制的 PWM（脉冲宽度调制）通道的开关。PWM 技术通过调节脉冲信号的占空比，可实现对背光亮度的精细调节。

# 启用 PWM通道控制背光亮度
backlight_pwm=on

4.9.15 backlight_pwm_chan

backlight_pwm_chan 参数用于选择 &pwm 节点上的具体通道，以用于背光控制。在已启用 backlight-pwm 的前提下，指定具体使用 哪个 PWM 子通道 输出背光控制信号（需与硬件匹配）

# 启用 PWM背光 控制器，选择其第 4 个子通道控制背光
backlight_pwm=on
backlight_pwm_chan=4

4.9.16 backlight_def_brightness

backlight_def_brightness 参数用于设置显示设备的默认亮度值，正常范围为 1_8。该参数决定了设备启动时或未进行手动亮度调节时的初始背光亮度水平（数值越大，亮度越高）。

#当前默认状态下亮度等级为 7，其配置方式如下
backlight_def_brightness=7

4.9.17 act_led_trigger

act_led_trigger 参数用于选择 LED 跟踪的活动模式，即控制背光 LED 的触发方式。默认值为 "default_on"（常亮模式），其他可能的值包括 "heartbeat"（心跳模式，LED 随系统心跳闪烁）、"timer"（定时器模式，按预设时间闪烁）、"none"（无触发，需手动控制）等。

# 无触发模式
act_led_trigger=none
# 常量模式
act_led_trigger=default_on
# 心跳模式
act_led_trigger=heartbeat
# 定时器模式
act_led_trigger=timer

4.9.18 color_order

color_order 参数用于精确指定 Taco 系列产品外接显示设备的像素颜色通道排列顺序，即屏幕硬件接收并解析 rgb（红、绿、蓝）三原色信号的物理顺序，直接决定显示画面的色彩还原准确性。若该参数配置与屏幕硬件实际颜色通道顺序不匹配，会导致显示画面出现色彩错乱（如红色显示为蓝色、绿色显示为红色等），甚至无法正常输出有效图像。 常见配置值及说明：color_order 的配置值需严格匹配屏幕面板的硬件规格（具体需参考屏幕供应商提供的 datasheet），Taco 系列产品支持的主流配置值如下表所示：

配置值	颜色通道顺序说明	适用场景举例
rgb	像素通道按 “红（R）→绿（G）→蓝（B）” 顺序排列	多数通用 LCD 屏幕、常规显示模组
bgr	像素通道按 “蓝（B）→绿（G）→红（R）” 顺序排列	部分 OLED 屏幕、特定工业显示面板
grb	像素通道按 “绿（G）→红（R）→蓝（B）” 顺序排列	部分低成本 LCD 模组、定制化屏幕
gbr	像素通道按 “绿（G）→蓝（B）→红（R）” 顺序排列	少数专用显示设备（如医疗、工控屏）

color_order=rgb

4.10 sd/emmc

4.10.1 sd / emmc

sd 与 emmc 参数用于分别控制系统中 SD 卡（Secure Digital Card）和 MMC 设备（MultiMediaCard，含 eMMC 嵌入式存储、MMC 扩展卡等）的硬件功能开关，决定对应存储设备是否在系统启动时被初始化并启用。适用于需要灵活开启 / 关闭存储接口的场景（如禁用闲置 SD 卡接口以降低功耗、仅启用指定 MMC 存储设备等）。

# 启用设备
sd=on
emmc=on
# 禁用设备
sd=off
emmc=off

4.10.2 sd_bus_width / emmc_bus_width

bus_width 参数用于配置 SDIO（Secure Digital Input/Output）总线的数据传输宽度，适用于 SD 卡、MMC 设备（含 eMMC）及其他 SDIO 接口设备，通过调整总线宽度优化数据传输速率。支持的常见宽度值为 1（1 位总线）和 4（4 位总线），部分硬件可能支持 8（8 位总线，多见于 eMMC 设备）。

# 配置总线宽度为 4 位（最常用配置，平衡速率与兼容性）
sd_bus_width=4
emmc_bus_width=4

# 配置总线宽度为 1 位（适用于低速率需求或兼容性调试场景）
sd_bus_width=1
emmc_bus_width=1

4.10.3 sd_clk_freq / emmc_clk_freq

clk_freq 参数用于配置 sd / emmc 工作时钟频率，通过调整时钟频率优化设备性能或满足特定场景需求（如降低时钟频率以减少功耗）。

# 配置 SD 控制器的工作时钟为 24 MHz
sd_clk_freq=24000000

# 配置 EMMC 控制器的工作时钟为 50 MHz
emmc_clk_freq=50000000

4.11 eth

4.11.1 eth_max_speed

eth_max_speed 参数用于设定以太网链路允许自动协商的 最大速率上限，限制以太网控制器与对端设备（如路由器、交换机）协商时可选用的最高传输速率，避免因硬件兼容性问题导致链路协商失败或传输不稳定。支持的逻辑配置值为 10（10Mbps）、100（100Mbps）、1000（1000Mbps，即千兆），系统默认值为 1000（优先协商千兆速率）。

# 配置最大协商速率为 100Mbps（适用于百兆交换机或低速网络场景）
eth0_max_speed=100
eth1_max_speed=100

4.11.2 eth_reset

eth_reset 参数用于定义以太网控制器的 复位引脚（Reset Pin），指定硬件上用于触发以太网控制器复位的 GPIO 引脚编号，确保系统启动时或异常后能通过该引脚正确复位以太网芯片，恢复正常工作状态。

# 配置以太网复位引脚为 GPIO41（具体引脚编号需结合硬件设计手册确认）
eth0_reset=41

4.11.3 eth_tx_delay

eth_tx_delay 参数用于调整以太网控制器 发送时钟（TXC_TX，即发送方向的时钟信号） 的时间偏移量，单位为皮秒（ps）。通过补偿时钟信号与数据信号的传输时延差，解决高速以太网（如千兆）中因 PCB 走线长度差异、信号干扰导致的发送时序不匹配问题，优化发送端的数据传输稳定性。

# 配置发送时钟偏移量为 200 ps（具体数值需根据硬件时序测试结果调整）
eth0_tx_delay=200

4.11.4 eth_rx_delay

eth_rx_delay 参数用于调整以太网控制器 接收时钟（TXC_RX，即接收方向的时钟信号） 的时间偏移量，单位为 皮秒（ps）。与 eth_tx_delay 对应，通过补偿接收端时钟与数据信号的时延差，解决高速以太网中接收时序不匹配问题，优化接收端的数据采样稳定性。

# 配置接收时钟偏移量为 150 ps（具体数值需结合硬件时序测试结果调整）
eth0_rx_delay=150

4.11.5 eth_mac

eth_mac 参数用于配置以太网控制器的物理地址（MAC 地址），支持为多个以太网接口（如 eth0、eth1）指定独立的 MAC 地址，确保网络设备在局域网中具备唯一标识，避免地址冲突导致的通信异常。

# 为 eth1 接口（对应设备树节点 &macb1）配置 MAC 地址
eth1_mac=00:1A:2B:3C:4D:5E

4.12 watchdog

watchdog 参数用于控制看门狗定时器（Watchdog Timer） 的启用状态。

# 开启 watchdog
watchdog=on
# 关闭 watchdog
watchdog=off

4.13 fan

4.13.1 fan_tempX（多级温控阈值）

• 功能：定义第 X 级冷却的温度触发点（单位：毫摄氏度，1℃ = 1000 毫摄氏度）
• 作用机制：当 SoC 温度超过 fan_tempX 时，系统将启用第 X 级冷却策略
• X 取值范围：通常为 1~N（当前系统的风级 N = 5）
• 配置示例：

fan_temp1=55000  # 55℃，第一级温控触发温度
fan_temp2=65000  # 65℃，第二级温控触发温度
fan_temp3=75000  # 75℃，第三级温控触发温度

4.13.2 fan_tempX_hyst（温度滞后参数）

• 功能：定义第 X 级温控的回差温度（单位：毫摄氏度）
• 作用机制：
  • 当温度从上方下降至 (fan_tempX _ fan_tempX_hyst) 时，系统切换至第 X_1 级冷却
  • 防止温度在阈值附近波动时风扇频繁切换档位
• 配置示例：

fan_temp1_hyst=5000  # 5℃ 回差
fan_temp2_hyst=5000  # 5℃ 回差

4.13.3 fan_minpwm（最小 PWM 值）

• 功能：当 SoC 温度低于 mintemp 时，风扇的 PWM 输出值
• 取值范围：0~255（对应 0%~100% 占空比）
• 配置示例：

fan_minpwm=30 # 最低转速设置为 PWM 值 30（约 12% 占空比）

4.13.4 fan_maxpwm（最大 PWM 值）

• 功能：当 SoC 温度高于 maxtemp 时，风扇的 PWM 输出值
• 取值范围：0~255（对应 0%~100% 占空比）
• 配置示例：

fan_maxpwm=255  # 最高转速设置为 PWM 值 255（100% 占空比）

4.14 bluetooth

4.14.1 bt

bt 用于控制设备内置蓝牙模块（如蓝牙 4.2/5.0/5.1 模组）的启用 / 禁用状态，是蓝牙功能初始化的核心控制参数，可直接调节蓝牙模块的上电流程、驱动加载及射频功能激活状态，决定设备是否能发起或接收蓝牙连接（如连接蓝牙音箱、键盘、传感器等外设）

# 启用
bt=on
# 禁用
bt=off

4.14.2 bt_baudrate

bt_baudrate 为蓝牙的工作的最大频率，默认是 3000000。

bt_baudrate=3000000

4.15 logging

4.15.1 base_addr

base_addr 指定内核日志缓冲区的物理内存起始地址。

4.15.2 total_size

定义日志缓冲区的总内存容量（字节），采用环形缓冲区设计，新日志覆盖旧日志。 默认值：64 KB（即 0 x 10000 字节）。 可存储日志记录数 = total_size ÷ record_size 默认 total_size = 64 KB 且 record_size = 16 KB 时，最多存储 4 条完整日志。

4.15.3 console_size

配置非 panic 日志（常规系统消息）的独立缓冲区大小。 默认值：0（常规日志与 panic 日志共用 total_size 缓冲区）。

模式	缓冲区分配有
默认（0）	所有日志（含 panic）共享 total_size 环形缓冲区，panic 日志可能被覆盖。
非零值（如 32 KB）	常规日志使用独立缓冲区（console_size），panic 日志使用剩余 total_size 空间。
注意：需隔离 panic 日志（如内核崩溃信息）时，设置 console_size 为非零值，确保关键错误日志不被常规消息覆盖：

console_size=32768  # 分配 32 KB 给常规日志，剩余 32 KB 用于 panic 日志

4.15.4 record_size

定义单次日志写入的固定块大小，决定每条日志的最大占用空间。 影响分析：

• 增大块大小：减少日志分割，但降低缓冲区可存储的日志条目数（如 total_size = 64 KB 时，record_size = 32 KB 仅能存储 2 条日志）。
• 减小块大小：可存储更多日志条目，但可能导致长日志被截断（若内容超过 record_size）。 典型配置：

record_size=8192  # 设置为 8 KB，适用于短日志高频输出场景（如嵌入式系统）

4.16 sata

sata 用于控制设备上 USB 3.0 转 SATA 接口的启用 / 禁用状态，该参数直接关联 USB 3.0 转 SATA 控制芯片（型号：asm1153E）的上电、驱动加载及功能激活，决定设备是否能通过该接口识别并使用外接 SATA 设备（如 SATA 硬盘、SSD）。

# disable
sata=on
# enable
sata=off

4.17 4g_5g_modem

用于控制设备内置 4G/5G 通信模组的启用 / 禁用状态，是设备蜂窝网络功能初始化的核心控制参数，通过修改该参数，可直接调节 4G/5G 模组的上电流程、驱动加载及功能激活状态，决定设备是否能接入蜂窝网络（4G LTE/5G NR）。

# disable
4g_5g_modem=on
# enable
4g_5g_modem=off

4.18 wifi

wifi 参数用于控制设备内置 Wi-Fi 模块的启用 / 禁用状态，是设备网络功能初始化的核心控制参数，通过修改该参数可直接调节 Wi-Fi 硬件的上电与功能加载状态。

# disable
wifi=on
# enable
wifi=off

4.19 USB

4.19.1 dr_mode

dr_mode（全称 Dual Role Mode，USB 双角色模式）是 USB 控制器设备树配置中的核心参数，用于定义 USB 端口的 工作角色—— 即该端口可作为 “主机（Host）”、“从机（Peripheral）” 或支持 “OTG（On-The-Go，动态切换角色）”，决定了 USB 端口与外部设备的通信方式。 取值：dr_mode 仅支持 “host”、“peripheral”、“otg” 三种取值，每种取值对应完全不同的硬件行为和应用场景，需根据实际需求选择。

1. dr_mode="host"（主机模式）

• 主动发起通信：主机负责生成 USB 总线时钟、发送枚举指令（识别外部设备类型）、分配地址；
• 提供电源：通常输出 5V 电压（电流根据硬件设计，如树莓派 USB 口最大提供 500mA），为从设备供电；
• 不可切换角色：一旦配置为 “host”，端口始终是主机，无法被其他设备（如电脑）识别为从设备。

2. dr_mode="peripheral"（从机模式）

• 被动响应：从机不生成时钟，仅接收主机的时钟和指令，按主机要求传输数据；
• 消耗电源：从机需从主机获取电源（如手机插电脑充电），或通过外部电源供电（不依赖主机供电）；
• 不可切换角色：一旦配置为 “peripheral”，端口始终是从机，无法连接 U 盘、鼠标等外设。

3. dr_mode="otg"

• 动态角色切换：通过 OTG 协议协商角色 —— 例如：
  • 连接 “主机设备”（如电脑）时，自动切换为从机；
  • 连接 “从机设备”（如 U 盘）且提供 OTG 供电时，自动切换为主机；
• 需硬件支持：OTG 模式要求 USB 控制器内置 OTG 逻辑，且端口需支持 “VBUS 检测”（判断外部是否有主机供电）和 “ID 引脚检测”（判断连接的设备类型）；
• 灵活性最高：兼顾 “被控制” 和 “控制外设” 的需求，是嵌入式设备的常用配置。